// ActionValidationException.java
package org.zjx.exception;

import org.zjx.core.GameAction;

/**
 * 动作验证异常(受检异常) - 当游戏动作验证失败时抛出
 *
 * 这个异常携带了关于验证失败的详细信息，包括错误代码和导致失败的
 * 具体动作，用于在决策过程中识别和处理无效动作。
 */
public class ActionValidationException extends Exception {
    // 错误代码，用于分类不同类型的验证失败
    private final String errorCode;
    // 导致验证失败的Action实例
    private final transient GameAction failedAction;

    /**
     * 使用错误代码、动作和消息构造异常
     *
     * @param errorCode 预定义的错误代码
     * @param action 导致失败的Action实例
     * @param message 描述错误的详细信息
     */
    public ActionValidationException(String errorCode,
                                     GameAction action,
                                     String message) {
        super(message);
        this.errorCode = errorCode;
        this.failedAction = action;
    }

    /**
     * 使用错误代码、动作、消息和原因构造异常
     *
     * @param errorCode 预定义的错误代码
     * @param action 导致失败的Action实例
     * @param message 描述错误的详细信息
     * @param cause 导致此异常的根本原因
     */
    public ActionValidationException(String errorCode,
                                     GameAction action,
                                     String message,
                                     Throwable cause) {
        super(message, cause);
        this.errorCode = errorCode;
        this.failedAction = action;
    }

    // 预定义错误码 - 用于分类不同类型的验证失败
    public static final String INVALID_STATE = "ACTION_001";      // 状态无效
    public static final String TIMEOUT = "ACTION_002";           // 超时
    public static final String PRECONDITION_FAILED = "ACTION_003";// 前置条件失败
    public static final String CONFLICT = "ACTION_004";          // 冲突

    // Getters - 提供对异常详细信息的访问
    public String getErrorCode() { return errorCode; }
    public GameAction getFailedAction() { return failedAction; }
}